home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 26 / Cream of the Crop 26.iso / utility / chang707.zip / CHANGE.DOC < prev    next >
Text File  |  1997-07-31  |  22KB  |  476 lines
  1. CHANGE.DOC                             1                           Jul 31, 1997
  2.  
  3. WIN95 AND WINNT NOTICE:  As with most DOS-based utilities, this program doesn't
  4. understand the weird subdirectories, long filenames,  invalid  characters  that
  5. are possible under Windows 95 and Windows/NT.   Both  operating  systems  alias
  6. long filenames into names like MYFILE~1.TXT and you will need  to  specify  the
  7. aliased versions of file names to process  them.   Under  some  file  structure
  8. systems in NT, the program may not work at all.
  9.  
  10. The CHANGE.EXE program allows you to make changes in binary or  text  files  of
  11. any size.  Features:
  12.  
  13.   * Can handle files of any size provided you have enough room on your disk  to
  14.     hold a copy of resulting file.
  15.   * Can be used to change text files or binary files.
  16.   * Can be used to remove trailing spaces from a file.
  17.   * Can specify different lengths for the input strings and the output strings.
  18.   * Can specify that the changes only be done in lines that include  a  certain
  19.     character string.  This selection string can be case-insensitive.
  20.   * Can handle up to 30 change requests at a time.
  21.   * Allows you to recurse through child subdirectories.
  22.   * For text input files, handles DOS text (all lines end with CR/LF), Mac text
  23.     (all lines end with CR), or Unix text (all lines end with LF) files.
  24.   * Can specify the  input/output  strings  as  ASCII  characters,  hexadecimal
  25.     values, or as decimal values.
  26.   * Handles the changes quickly.
  27.   * Can either replace the original file with the resulting file or else create
  28.     a new changed file (using /Noutfile specification).
  29.   * Changes can be interactively verified before they are made.
  30.   * Changes can be entered in any of the following ways:
  31.        - from the command line (one TO/FROM pair allowed)
  32.        - interactively (one TO/FROM pair allowed)
  33.        - from a controlfile (up to 30 TO/FROM pairs allowed)
  34.   * Boolean operators can be used if the TO/FROM pair  is  specified  from  the
  35.     command line; for example:
  36.        CHANGE TEST.TXT /FROM One /TO Many /IN Apples OR Oranges
  37.   * The input file specification can  include  standard  DOS  wildcards  or  an
  38.     external file (@listfile) containing the files to  be  processed  (although
  39.     either prohibits using the /Noutfile feature).
  40.   * The input  change  specification  can  end  with  "*"  in  which  case  all
  41.     subsequent characters are changed to the end of the line.  For example:
  42.        CHANGE TEST.TXT /FROM DEVICE=C:\BIN\AD* /TO DEVICE=C:\BINNEW\ADNEW.COM
  43.   * The input change specification can include a column specification  so  only
  44.     characters that fall within a given range of columns are changed.
  45.   * You can exclude files from processing based on file attributes.
  46.   * Can be used to eliminate lines that you don't want.  For example:
  47.        CHANGE TEST.TXT /FROM DEVICE=C:\DOS\SMARTDRV.EXE /TO NULL /ZAPNULL
  48.   * Pressing escape stops the program early.
  49.  
  50.  
  51. Specifying parameters:
  52.  
  53. Parameters for this program can be set in the following ways.  The last setting
  54. encountered always wins:
  55.   - Read from an *.INI file (see BRUCEINI.DOC file),
  56.   - Through the use of an environmental variable (SET CHANGE=whatever), or
  57.   - From the command line (see "Syntax" below)
  58.  
  59.  
  60.  
  61. CHANGE.DOC                             2                           Jul 31, 1997
  62.  
  63. To/From/In Specifications:
  64.  
  65. The CHANGE program allows you to specify three parts to a change request:
  66.  
  67.   * The text to be replaced
  68.   * The text to replace it with
  69.   * Optionally, a string which the line must contain before the change is made
  70.  
  71. For example, in the following two lines:
  72.  
  73.         The quick brown fox jumped over
  74.         the lazy brown dog.
  75.  
  76. the program allows you to replace the string "brown" with the string "red" only
  77. in lines that contain the string "fox" (so "brown fox" becomes "red fox"). This
  78. would change the "brown" in the first line but not the one in the second line.
  79.  
  80. In order to enter your change request(s), you can use one of three methods:
  81.  
  82.   *  Enter it from the command line using /FROM string, /TO string, /IN string
  83.   *  Let the program prompt you for the /FROM, /TO, and /IN specifications
  84.   *  Use a control file
  85.  
  86. The control file is a regular ASCII text file (created with any  text  editor).
  87. It can contain up to 30 change requests (the other two  approaches  only  allow
  88. for one).  Each line of the control file should consist of records  of  one  of
  89. four record types:
  90.  
  91.   *  blank lines or those beginning with semi-colons, colons, or single  quotes
  92.      are treated as comments.
  93.   *  lines  beginning  with  "-F"  or  "-f"   provide   FROM   options.    FROM
  94.      specifications must precede TO specifications.
  95.   *  lines beginning with "-T" or "-t" provide TO options.   TO  specifications
  96.      must precede IN specifications (if any are used).
  97.   *  lines beginning with "-I" or "-i" provide IN options.  These are optional;
  98.      if not provided, all lines will be searched for the FROM string.   Any  IN
  99.      request forces /TEXT mode to be invoked.
  100.  
  101. If more than one set of FROM/TO/IN records is provided,  the  -F  specification
  102. must  precede  the  others.   Each  option  is  local  to  a  given  FROM/TO/IN
  103. specification.  For example:
  104.  
  105.         ; Sample control file
  106.         -FPRINT
  107.         -TPrinting
  108.         -I"
  109.         -fUSING
  110.         -tused
  111.  
  112. contains two FROM/TO/IN specifications.  "PRINT" will be changed to  "Printing"
  113. in any line with a double quote.  "USING" will be  changed  to  "used"  in  all
  114. lines; no -I option is applied for the second FROM/TO/IN specification.
  115.  
  116.  
  117. CHANGE.DOC                             3                           Jul 31, 1997
  118.  
  119. If you want to specify your from/to request from the command line  and  any  of
  120. your strings contains  one  or  more  spaces,  enclose  the  string  in  double
  121. quotation marks.  For example:
  122.  
  123.         CHANGE BUGBUNNY.TXT /FROM "Elmer Fudd" /TO "Daffy Duck"
  124.  
  125. The FROM/TO/IN specifications can include any text characters.  They  can  also
  126. contain ASCII codes, created either using the Alt key in combination  with  the
  127. numeric keypad (for example, Alt-228 to get  a  Sigma  character)  or  else  by
  128. embedding a hexadecimal code (in the form &Hxx) or a decimal code (in the  form
  129. \nnn) in the text.  These codes are described in the  BRUCEHEX.DOC  file.   For
  130. example, to change a double carriage return/line  feed  to  a  single  carriage
  131. return/line feed, you could say:
  132.  
  133.         -F&H0D0A0D0A
  134.         -T&H0D0A
  135.  
  136. (Note that the above example would require you to use the  /BINARY  option--the
  137. default-- since the lines encountered will extend beyond line boundaries.)
  138.  
  139. If you need to follow a hexadecimal specification with normal text  characters,
  140. follow the hex spec with one space (which CHANGE will ignore).  For example,
  141.  
  142.         -F&H0c Hi!
  143.         -T&H0d0a Bye!
  144.  
  145. DOS considers certain characters ("|" and ">") to be pipe characters  and  will
  146. strip them away from the command line before CHANGE gets them.  If you need  to
  147. specify a change that includes these characters and you want to use the command
  148. line for it, use the hexadecimal  or  decimal  codes  instead.   Alternatively,
  149. putting them in quotes seems to usually work.
  150.  
  151. If the "/FROM string" specification ends with an asterisk (for example,  "/FROM
  152. BRUCE*"), the program will look for any  instance  of  the  string  before  the
  153. asterisk and replace that string and all subsequent characters in the line with
  154. the designated "/TO string".  Asterisks embedded within the string (as  opposed
  155. to being the trailing  character  of  the  string)  will  be  read  as  regular
  156. characters.  If you  actually  want  to  replace  an  asterisk  as  a  trailing
  157. character, use the &Hxx or \nnn conventions.  Specifying a wildcard  like  this
  158. puts you into /TEXT mode automatically.  Wildcards cannot be used in  the  "/TO
  159. string" specification.
  160.  
  161. The "/FROM string" parameter can include a column indicator  after  the  string
  162. (and the asterisk if used).  A single column can be specified in which case the
  163. string to be changed has to be found in that specific column:
  164.  
  165.         CHANGE TEMP.X /FROM ";" 1 /TO NULL /NTEMP.X2
  166.  
  167. Alternatively, the column specification can include a range  of  columns.   The
  168. "from" specification has to start  within  that  range  (although  it  can  end
  169. outside of that range).  For example:
  170.  
  171.         CHANGE TEMP.X /FROM "\" 3/50 /TO "/" /NTEMP.X2
  172.  
  173.  
  174. CHANGE.DOC                             4                           Jul 31, 1997
  175.  
  176. To remove a string entirely, use the  -T  without  anything  after  it  or  use
  177. "-TNULL" or "/TO NULL" from the command line.  If  the  /ZAPNULL  parameter  is
  178. provided, if the entire line is reset to nothing, the line will not be  written
  179. out at all.  This allows you to drop lines if necessary.
  180.  
  181. As far as case-sensitivity is concerned, the /FROM and /IN  specifications  are
  182. case-sensitive unless /I is  specified.   The  /TO  specification  is  *always*
  183. case-sensitive.
  184.  
  185.  
  186. Syntax:
  187.  
  188.     CHANGE { filespec | (filelist) | @listfile } [ /ATTR=attribs ] [ /S ]
  189.       [ /-PROMPT ] [ /Cctlfile | /FROM string /TO string [ /IN search ] ]
  190.       [ /LINES { line1-line2 | line1 linect } ... ] [ /V ] [ /I ]
  191.       [ /Noutfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ] ]
  192.       [ /Frptfile ] [ /Ttempfile ] [ /TRIM ] [ /ZAPNULL ]
  193.       [ /TEXT | /BINARY ] [ /VERIFY ] [ /Q | /Qn ] [ /W | /W0 | /-W ]
  194.       [ /MONO ] [ /Iinitfile | /INULL ] [ /-ENV ] [ /? ] [ /?&H ]
  195.  
  196. where:
  197.  
  198. "filespec" tells the routine which file or files are to be processed.   It  can
  199. include path  information  if  desired.   It  can  also  include  standard  DOS
  200. wildcards as long as the /Noutfile parameter is not specified.  If a  /Noutfile
  201. parameter is not provided, the input files are overwritten by  the  results  of
  202. this program.  If you'd like to process a lot of files  and  still  create  new
  203. files, use the DOS FOR command instead.  Try something like this:
  204.  
  205.         FOR %A IN (*.TXT) DO CHANGE %A /FROM "A" /TO "B" /N\TEMP\%A
  206.  
  207. "(filelist)" allows you to specify multiple files  to  be  processed  from  the
  208. command line.  File names should be separated  by  spaces.   They  may  include
  209. drive, path, and wildcard information.  Remember that a  command  line  in  DOS
  210. cannot exceed 127 characters so you're limited as to how  many  different  file
  211. specifications you can provide in this fashion.
  212.  
  213. "@listfile" allows you to have a variety of file specifications saved in a text
  214. file named "listfile".  Each line in  the  file  should  consist  of  one  file
  215. specification, each of which can include a path and wildcards if desired. Blank
  216. lines and lines beginning with semi-colons, colons, or quotes are ignored.
  217.  
  218. "/ATTR=attribs" allows you to specify a combination of attributes that you want
  219. considered.  You can specify any combination of R (read-only),  H  (hidden),  S
  220. (system), or A (archive bit).  Precede any character(s)  with  "-"  to  exclude
  221. instead of include.  Unlike with  the  DOS  DIR  command,  the  inclusions  and
  222. exclusions are subject to "OR" conditions; /ATTR=HS will retrieve any file that
  223. is either hidden or a system file or both.   You  can  specify  "/ATTR=ALL"  to
  224. specify that all files are to be processed.  Initially defaults to /ATTR=-H-S-R
  225. (exclude any files that are hidden, system, or read-only).
  226.  
  227. "/S" processes files in subdirectories off the specified subdirectory. This  is
  228. a powerful option but it also allows you to do  dumb  things  that  you  really
  229. shouldn't do (like change every "A" on your hard disk to  "a")  so  be  careful
  230. with it.  Initially defaults to "/-S".
  231.  
  232.  
  233. CHANGE.DOC                             5                           Jul 31, 1997
  234.  
  235. "/-PROMPT"  suppresses  the  normal  "Cascading   subdirectory   parameter   /S
  236. specified.  Okay?" prompt is cascading ("/S" parameter) is specified. Initially
  237. defaults to "/PROMPT".
  238.  
  239. "/Cctlfile" specifies a control file with the  change  commands  to  make.  See
  240. "To/From/In Specifications" above.
  241.  
  242. "/FROM string /TO string [ /IN search ]" allows  you  to  specify  the  from/to
  243. parameters on the control line.  See "To/From/In  Specifications"  above.   The
  244. "/IN search" parameter invokes text mode and  is  not  recommended  for  binary
  245. files.
  246.  
  247. "/LINES line1-line2" says to restrict the search to lines between line  numbers
  248. line1 and line2 inclusive.  You can have multiple line requests  in  any  order
  249. such as "/LINES 1-10 90-100 30-50".  The routine  skips  all  lines  after  the
  250. largest line number is encountered.  The "/LINES" parameter invokes  text  mode
  251. and is not recommended for binary files.  Defaults to "/LINES 1-9999999".
  252.  
  253. "/LINES line1 linect" says to restrict the search to lines beginning with line1
  254. and continuing for a total of linect lines.  So "/LINES 10 20" is actually  the
  255. same as "/LINES 10-29".  The "/LINES" parameter invokes text mode  and  is  not
  256. recommended for binary files.
  257.  
  258. "/V" says to find those items that do NOT match the specification.
  259.  
  260. "/-V" is the opposite of /V and is typically the default.
  261.  
  262. "/I" says to make it a case-insensitive search.
  263.  
  264. "/-I" is the opposite of /I and is typically the default.
  265.  
  266. "/Noutfile" is the name of the new file to  create.   If  a  /Noutfile  is  not
  267. specified, the source document (infile) will be replaced by the changed file.
  268.  
  269. "/OVERWRITE" says to write  over  the  outfile  (if  requested)  if  it  exists
  270. already.
  271.  
  272. "/-OVERWRITE" says to abort if the outfile exists already.
  273.  
  274. "/OVERASK" says to ask if the outfile exists already.  This is the default.
  275.  
  276. "/Frptfile" is the name of a file to contain all changed  lines.   This  allows
  277. you to see what the lines were changed  to  for  verification  purposes.   This
  278. option automatically invokes text mode and is not recommended for binary files.
  279. The report file is always appended to so new lines are written at  the  end  of
  280. any existing report file.
  281.  
  282. "/Ttempfile" is the name of the temporary file to create.  The  actual  changes
  283. are written to a temp file and then the source file is replaced with  the  temp
  284. file is everything works and there were actually changes to  be  found  in  the
  285. source document.  By default, the temp file is called {CHANGE}.TMP  and  it  is
  286. written to the same path as the input file.  The temporary file will be as  big
  287. as the final file is.  If you don't have enough room  for  it  to  be  on  your
  288. source disk, specify another temporary file name with  a  different  path  (for
  289. example, "/TG:\TEMP.TXT").
  290.  
  291.  
  292. CHANGE.DOC                             6                           Jul 31, 1997
  293.  
  294. "/TRIM" says to remove trailing spaces from the end of each line. Automatically
  295. forces you into TEXT mode.
  296.  
  297. "/-TRIM" is the opposite of /TRIM and is the default.
  298.  
  299. "/ZAPNULL" says that if the output line is changed and ends up empty, then  the
  300. line should be dropped entirely from the output file.  Requires you  to  be  in
  301. TEXT mode.
  302.  
  303. "/-ZAPNULL" retains all lines.  This is initially the default.
  304.  
  305. "/TEXT" puts you into TEXT mode.  TEXT mode means that all data in the file are
  306. read in and processed as separate text records.  Alternatively, the file can be
  307. processed in BINARY mode in which case the file is read  in  in  large  blocks.
  308. BINARY mode is quicker and is required for binary files like EXE and COM files.
  309. TEXT mode may or may not work if you use it on a binary  file.   TEXT  mode  is
  310. *required* if you specify any of the following options:
  311.  
  312.         * an /IN (or -I) request
  313.         * /LINES
  314.         * /Frptfile
  315.         * /TRIM
  316.         * /VERIFY
  317.  
  318. Under /TEXT mode, the program will read DOS text (lines end  with  CR/LF),  Mac
  319. text (lines end with CR), or Unix text (lines end  with  LF)  files.   However,
  320. under /TEXT mode, all lines will be written out as DOS  text  (lines  end  with
  321. CR/LF).
  322.  
  323. "/BINARY" is the opposite of TEXT mode.  It's  faster  than  TEXT  and  is  the
  324. default for CHANGE.  It is overridden if you  specify  certain  options  listed
  325. above.
  326.  
  327. "/VERIFY" says to prompt you before changing  any  lines.   You  are  asked  to
  328. confirm that you in fact want to make each change requested.  "/VERIFY" invokes
  329. text mode and is not recommended for binary files.
  330.  
  331. "/-VERIFY" is the opposite of /VERIFY and is the default.
  332.  
  333. "/Q" turns off the record-by-record status report.  (In /TEXT mode, the  status
  334. records appear every 25 records.  In /BINARY mode, the  status  records  appear
  335. every 6000 bytes.)
  336.  
  337. "/Qn" shows a status message every n-number  of  records.   This  only  effects
  338. /TEXT processing, not binary processing.  The default is "/Q10".
  339.  
  340.  
  341. CHANGE.DOC                             7                           Jul 31, 1997
  342.  
  343. "/W" says to pause with a "Press any key to continue" message after the program
  344. finishes if any hits were found.  This parameter is ignored if redirection  out
  345. is being used.
  346.  
  347. "/W0" says to pause afterward whether any hits were  found  or  not.   This  is
  348. initially the default if the program is  run  under  Windows3.1  or  Windows95.
  349. CHANGE won't detect if you're running under Windows NT though; you can manually
  350. specify this parameter if the window closes up on you before you can  read  the
  351. results.  This parameter is ignored if redirection out is being used.
  352.  
  353. "/-W" says to not pause afterward at all.  This is initially the default if the
  354. program is run under DOS or Windows NT.
  355.  
  356. "/MONO" (or "/-COLOR") does not  try  to  override  screen  colors.   Initially
  357. defaults to "/COLOR".
  358.  
  359. "/COLOR" (or  "/-MONO")  allows  screen  colors  to  be  overridden.   This  is
  360. initially the default.
  361.  
  362. "/Iinitfile" says to read an initialization file with the file name "initfile".
  363. The file specification *must* contain a period.  Initfiles are described in the
  364. BRUCEINI.DOC file.  Initially defaults to "/ICHANGE.INI".
  365.  
  366. "/INULL" says to skip loading the initialization file.
  367.  
  368. "/ENV" says to look for %var% occurrences  in  the  command  line  and  try  to
  369. resolve any apparent environmental variable references.  See  BRUCEINI.DOC  for
  370. more information.  This is initially the default.
  371.  
  372. "/-ENV" says to skip resolving apparent %var% occurrences in the command  line.
  373. Initially defaults to "/ENV".
  374.  
  375. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  376.  
  377. "/?&H" gives you a hexadecimal and decimal conversion table.
  378.  
  379.  
  380.  
  381. CHANGE.DOC                             8                           Jul 31, 1997
  382.  
  383. For search, the syntax is:
  384.  
  385.   [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
  386.  
  387. where:
  388.  
  389.   ( and )     are used to group items
  390.   search_item is shown below
  391.   boolean     is AND, OR, or XOR (NOT is included with search_item)
  392.  
  393. for search_item, the syntax is:
  394.  
  395.   [ NOT ]  "string" [ column ]
  396.  
  397. where:
  398.   NOT         is obvious
  399.   string      the string to search; the quotation marks are typically not
  400.               required unless the string contains a space or a reserved word
  401.               or begins with a slash ("/")
  402.   column      is the column in which the string must be found.
  403.  
  404. So, let's cover some examples:
  405.  
  406.         CHANGE TEST.TXT /FROM Apple /TO Banana /IN "Bugs Bunny" OR "Elmer Fudd"
  407.  
  408. Quotes are needed around a string if it begins with a slash:
  409.  
  410.         CHANGE TEST.TXT /FROM "/1997" /TO "/1998" /IN "Revised"
  411.  
  412. The above changes the string "Apple" to "Banana" in any lines that have  either
  413. the text "Bugs Bunny" or "Elmer Fudd" in them.
  414.  
  415.         CHANGE TEST2.TXT /FROM Bugs /TO Bunny /IN (Apples or Oranges) AND NOT
  416.            Pears /LINES 1-1000
  417.  
  418. The above changes "Bugs" to "Bunny" in the first thousand lines  of  TEST2.TXT.
  419. The line itself must contain the words "Apples" or "Oranges" in  them  and  any
  420. lines are ignored that contain "Pears".  Note that the quotes around the search
  421. words are not required unless the words include spaces or unless they could  be
  422. confused with some other keywords.  "CHANGE TEST3.TXT /FROM Bugs /TO Bunny  /IN
  423. OR OR AND" might cause the program to get confused since "OR" and "AND",  which
  424. you want to look for, are also keywords.
  425.  
  426.         CHANGE /I TEST.TXT /FROM One /TO Many /IN "Bugs Bunny" AND Martians
  427.  
  428. The above changes "One" to "Many" is any lines that contain both  "Bugs  Bunny"
  429. and "Martians".  The search is case-insensitive  so  lines  with  either  "BUGS
  430. BUNNY" and "Bugs Bunny" will be changed.
  431.  
  432. NOTE:  THIS EXTENDED SEARCHING CAPABILITY IS SUPPORTED ONLY  FOR  /IN  REQUESTS
  433. MADE FROM THE COMMAND LINE.  IT IS NOT SUPPORTED IN EITHER THE  CTLFILE  OR  IN
  434. THE INTERACTIVE TO/FROM SELECTION MODE.
  435.  
  436.  
  437.  
  438. CHANGE.DOC                             9                           Jul 31, 1997
  439.  
  440. Return codes:
  441.  
  442. CHANGE returns the following ERRORLEVEL codes:
  443.  
  444.         0 = no problems, changes made
  445.         1 = no problems, nothing found to change
  446.       253 = routine aborted early
  447.       254 = internal problems
  448.       255 = syntax problems, file not found, or /? requested
  449.  
  450.  
  451. Author:
  452.  
  453.                         Bruce Guthrie
  454.                         Room H-4885
  455.                         U.S. Dept of Commerce/ESA/STAT-USA
  456.                         Washington, DC 20230
  457.  
  458.                         voice: (202) 482-3234
  459.                         e-mail: bguthrie@doc.gov
  460.  
  461. You  may  freely  copy  and  re-distribute  this  program;  however,  the  U.S.
  462. Department of Commerce neither guarantees  nor  assures  compatibility  of  the
  463. program with all computer software or hardware.
  464.  
  465. Additional information about this and other Bruce Guthrie programs can be found
  466. in the file BRUCE.DOC which should be included in the original ZIP  file.   The
  467. recent change history for this and  the  other  programs  is  provided  in  the
  468. HISTORY.ymm file which should be in the same ZIP file where "y" is replaced  by
  469. the last digit of the year and "mm" is the two  digit  month  of  the  release;
  470. HISTORY.611 came out in November 1996.  This same naming convention is used  in
  471. naming the ZIP file (CHANGymm.ZIP) that this program was included in.
  472.  
  473. Please provide an Internet e-mail address on all correspondence.
  474.  
  475. 
  476.